CD Ware Multimedia 1995 May/cd Ware (Juegos) Epimundo.iso/DOS/C/INPUTS.ZIP/INPUT.DOC

Text File | 1991-02-25 | 16.3 KB | 390 lines

     The functions presented here add to the programmer's tools or
libraries functions that emulate Clipper's input functions for character,
numeric, date, and logical field input with more functionality. The
interface is simple and straightforward.  Nested input is also possible
which does not have to be emulated as in Clipper's input functions.  If
nested input is done, you don't have to worry about the cursor location on
return from nested input as the functions will restore the cursor on
return.  All functions can be exited by pressing the escape key, tab key,
or enter key. If more input functions follow, input will go to the next
field for input.  The only date format accepted is MM/DD/YY.  If a date
field is being input, only a valid date will be accepted.  If an invalid
date is forced (by leaving the field), the date array is set to all spaces
(ie: '  /  /  ').  This makes for very versatile data input that increases
the programmer's proficiency and adds a more professional input package
that cannot be achieved from standard library input routines.  The code is
small (about 8K) and does not create tremendous overhead in the executable
file.  The code is available in object format only.  The SMALL model is in
public domain for your use.  The LARGE model objects can be purchased for a
fee of $19.95 plus $3.00 shipping and handling.  California residents add
applicable sales taxes.  Mail orders to:

                        LPC Software
                        1250 Cloverglen Dr.
                        Valinda, Ca.  91744


----------------------------------------------------------------
     These are the six functions that you need to use.  One each for the
different types of inputs that you create.  The types of inputs accepted
are:
        string : inputs characters and character numbers
         alpha : inputs alpha characters only
       logical : inputs logical only (Y or N)
      long int : inputs long integers only (-2,147,483,648 to
                               2,147,483,647)
        double : inputs floating point numbers up to 80 digits
          date : inputs a valid date with format MM/DD/YY

Plus two lower level function:
1.  waitkey() : simulates getch() filtering out exception keys.  This
function takes no arguments and returns nothing.
2.  getKeyExtended() : This function takes no arguments and returns a
'keycodes' structure defined in the INPUT header file.  This function can
be used to control a while loop looking for only one key on the keyboard.
See example below.

     Each input function is prototyped in the INPUT.H file.   This is what
the prototypes look like:

      void    inputString(char *, int, void (*func)(char));

      void    inputAlpha(char *, int, void (*func)(char));

      char    inputLogical(char, void (*func)(char));

      long    inputLong(int, void (*func)(char));

      double  inputDouble(int, int, void (*func)(char));

      void    inputDate(char *, void (*func)(char));

Notice the declaration "void (*func)(char)" in the argument list for these
prototypes.  These are the functions that you write that will be executed
when an exception key is pressed, ie: F1, F2, <ALT><A>, etc.  If one of
these keys is pressed, the function passed will be executed.  This is how
nested input can be achieved or help screens popped up. No trapping is done
for the <CTRL><C> or <CTRL><BREAK> key.  If one of these two keys is
pressed, the program will abort unless you have redefined these exception
handlers elsewhere in your code or have disabled them.  Consult your
reference manuals on how to do this.


'void (*func)(char)' further defined:
   This is a pointer to a function that accepts a character (the exception
key pressed) that returns nothing.  The name 'func' is arbitrary and must
be prototyped as 'void func(char)' in your main file or a header file; or
'void handler(char)'; or whatever name you want to use.  This function will
be called if an exception key is pressed while entering data into one of
the types above and must exist even if it does nothing.  Here is a complete
example that demonstrates this:

void func(char);            /* The prototype for your function */
long LongIntegerNumber;     /* A variable to place an int      */

void main(void) {
   LongIntegerNumber = inputLong(10, func);
   do_whatever_with(LongIntegerNumber);
}

void func(key_received) {
   int i:   /* This will convert the character to an int */
   i = key_received;
   if (i == F1)
      do_whatever_F1_is_supposed_to_do();
   return;
}

A handler must be defined for each of the six high level input functions
even though is doesn't do anything. All high level functions begin with the
word "input".  If you want nothing done in your handler, simply put a
return statement inside.  For example:

   void func(key_received) {
      return;
   }

and pass this function as an argument to the high level input function.

     There is also two other functions in the library for your use.  These
functions are waitkey() and getKeyExtended().  waitkey()'s prototype is
'void waitkey(void)' and is in the INPUT header file.  If you create nested
input, it is highly recommended that you use this function for a keypress
to return to the calling function.  If you use getch() or any other
function and the user presses a function key consecutively without a call
to another nested input function, unpredictable results may occur.  The
prototype for getKeyExtended is 'struct keycodes getKeyExtended(void) and
is also in the INPUT header file.  Do not mix the standard library input
routines within these routines.  Standard input can be used with no problem
in all modules as long as one of these six input routines aren't being used
for input.

////////////////////////////////////////////////////////////////
            The functions usage are described below.
////////////////////////////////////////////////////////////////
To input a string:
   Use the function - void inputString(char *, int, void (*func)(char));
   This function takes three parameters which are (1) a pointer to an
array, (2) the size of the array (always allow one character more in the
array for the terminating null character in the string, use sizeof), and
(3) the function name to be executed for an exception key.  In the long
integer example above, the function name is 'func'.  Here is another
example:

   #include "input.h"
   void StringHandler(char);
   char string[21];

   void main(void) {
      inputString(string, sizeof string, StringHandler);
      printf("string is: %s\n", string);
   }

   void StringHandler(char excpt_key) {
      printf("\nHandler executed with key %d\n", excpt_key);
      return;
   }

This example simply inputs the string.  If an exception key is pressed
while inputting the string, the StringHandler is executed and prints the
message "Handler executed with key 59" if F1 was pressed during input.


////////////////////////////////////////////////////////////////////////
To input an alpha string:
   Use the function - void inputAlpha(char *, int, void (*func)(char));
   The format for usage is exactly like that of the input string function.
The only characters that are allowed to be input are the letters A thru Z
and a thru z.


////////////////////////////////////////////////////////////////////////
To input a logical:
   use the function - char inputLogical(char, void (*func)(char));
   This takes two parameters which are (1) the actual character field where
the logical input is to be placed, and (2) a function name that is to be
executed if an exception key is pressed.  Here is an example:

   #include <input.h>
   void LogicalHandler(char);  /* your handler prototype  */
   char YesNo;                 /* field for logical input */
   YesNo = 'Y';

   void main(void) {
      YesNo = inputLogical(YesNo, logHandler);
      if (YesNo == 'Y') {
         .
         .
      } else {
         .
         .
      }

   void logHandler(key) {
      int the_key;

      the_key = key;  /* Remember to convert to int */
      if (the_key == F1) {
         .
         .
      }
         .
         .
      if (the_key == F10)
         exit(0); /* Standard library function will close all files. */
      return;
   }

It is not important that YesNo be set to a 'Y' or 'N'.  If YesNo is null
when this function is executed, it will be set according to the key pressed
for logical input.  If it is not set when called and the user hits the
escape key or return key without entering anything, it will be set to 'N'
otherwise 'Y'.


////////////////////////////////////////////////////////////////////////
To input long integers:
   Use the function - int inputLong(int, void (*func)(char));
   This function takes two parameters which are (1) the number of digits to
be input.  This number cannot exceed twelve (max digits would be ten
characters in 2147483648 plus a preceding minus sign plus a terminating
null character all used internally within the inputLong function.  (2) The
second parameter is a function to execute if an exception key is pressed.
The inputLong() function will return the value of the long integer input.
The range of this functions return value is -2,147,483,648 to 2,147,483,647
inclusive. Make sure that you do not allow input beyond these ranges.  This
can be achieved by passing a smaller number of digits to be input thereby
limiting the range of input.  If you pass twelve as the number of digits to
be input, there is no guarantee that the operator will not input a '9' as
the first digit followed by nine more digits well exceeding the range for a
long integer and still being able to enter more.  For numeric input beyond
the ranges of this function, use the inputDouble() function. If nothing is
input, zero is return.  An example of usage follows:

   #include "input.h"
   void handler(char);    /* prototype your handler */
   long LNumber;

   long main(void) {      /* don't know why anybody would do this */
      LNumber = inputLong(6, handler);
      return(Number);
   }

   void handler(key) {    /* your handler */
      if (key == F10)     /* will quit the program if F10 is pressed */
         exit(0);
      return;
   }


////////////////////////////////////////////////////////////////////////
To input doubles:
   use function - double inputDouble(int, int, void (*func)(char));
   This function takes three parameters that are (1) the number of digits
that will be accepted including the decimal point and terminating
character.  If the number is greater than 80, the function will return a
zero. So the maximum field size for input on the screen is eighty.  (2) The
second parameter is the number of decimal places that will be accepted.
For dollar amounts, this value would be two. (3) The third parameter is the
function to be executed for an exception key.  For example:

   #include "input.h"
   void anotherhandler(char);   /* prototype your function */
   double Number;

   void main(void) {
      Number = inputDouble(20, 2, anotherhandler)
      printf("\n%f\n", Number);
   }

   void anotherhandler(key) {
      if (key == F1)
         doHelpScreen();   /* defined elsewhere in your program */
      if (key == F10)
         exit(0);          /* program will exit here if F10 pressed */
      return;
   }

This function will return a double and assigned it to a variable.
////////////////////////////////////////////////////////////////////////
To input dates:
   use function - void inputDate(char *, void (*func)(char))
   This function take two parameters that are (1) a string that holds the
array "  /  /  ".  This is in fact an array of nine characters.  Eight are
visible and the ninth is the terminating null character '\0'.  Only valid
dates are accepted and will adjust for leap years.  The only format
accepted is MM/DD/YY.  For the year 2000, YY would be 00.  Here is an
example:

   #include "input.h"
   void datefunc(char);         /* Your exception handler */
   char date[] = "  /  /  ";    /* Must have this format  */

   void main(void) {
      inputDate(date, datefunc);
         .
         .
      return;
   }

   void datefunc( ch ) {
      int key;

      key = ch;
      do_whatever_with( key );
      return;
   }

////////////////////////////////////////////////////////////////////////
To wait for a keypress:
   use function - void waitkey(void)
   This function will filter out any exception keys and will return only if
A-Z, 0-9, ENTER, SPACE, TAB, or RETURN is pressed. For example:

   #include <conio.h>   /* for clrscr() */
   #include "input.h"
   void main(void) {
      clrscr();
      waitkey();
      return;
   }

This simple program will clear the screen and wait for a key to be pressed.
Once a key is pressed, the program will exit back to DOS.
////////////////////////////////////////////////////////////////////////
To get a key value from the keyboard:
   use function struct keycodes getKeyExtended(void)
   This function will return the key pressed or the extended key pressed as
defined by the keycodes structure in the INPUT header file.  If a normal
key is pressed, its value is placed in the keycodes key location. If an
exception key is pressed (ie: F1, F2, ALT1, etc.), its value will be placed
in the keycodes scancode location.  Here is an example on how to use this
function:

   #include "input.h"

   void main(void) {

      struct keycodes input;   /* declare a structure */

      do {
         input = getKeyExtended();
      } while (input.key != 'q');
   }

This small program will run until a 'q' is pressed on the keyboard.
////////////////////////////////////////////////////////////////////////
     If your handler functions do anything such as popping up a window or
nested input or simply displays a message on the screen in any given
location, the cursor will be restored to the original position on the
screen from where the handler function was called during input.  All the
high level input functions do this so you can write your handler functions
without having to worry about the cursor when inputting a field.
////////////////////////////////////////////////////////////////////////
If you are interested in purchasing the large model library, send a check
for $19.95 plus $3.00 for shipping and handling.  You will receive both
the small model and large model libraries.  California residents add
applicable sales tax.  Make check out to: LPC Software and mail to:

                    LPC Software
                    1250 Cloverglen Dr.
                    Valinda, Ca. 91744

If you are a Compuserve user, questions and suggestions may be sent via
E-MAIL to 74106,3500.

         ----------------end-of-author's-documentation---------------

                        Software Library Information:

                   This disk copy provided as a service of

                        The Public (Software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  The P(s)L cannot de-
         bug programs over the telephone.

         Disks in the P(s)L are updated monthly, so if you did not get
         this disk  directly from the P(s)L,  you should be aware that
         the files in this set may no  longer be the current versions.

         For a copy of the latest monthly software library newsletter
         and a list of the 2,000+ disks in the library, call or write

                        The Public (Software) Library
                              P.O.Box 35705
                           Houston, TX 77235-5705
                               [phone]